Skip to main content

Microsoft Azure

This guide outlines the steps required to configure Microsoft Azure's Speech service for use with the application's voicemail transcription service.

Azure uses a straightforward API Key and Region for authentication, which is simpler to configure than Google's OAuth 2.0 method.

Prerequisites​

  • A Microsoft Azure account. If you don't have one, you can create a free account.

Step 1: Create an Azure Speech Service Resource​

First, you must create a Speech service resource within your Azure account. This resource will provide you with the dedicated API endpoint and keys.

  1. Log in to the Azure Portal: Navigate to https://portal.azure.com/.

  2. Create a Resource:

    • In the top search bar, type "Speech services" and select it from the results.
    • Click the Create button.

  3. Configure the Resource: Fill out the creation form with the following details:

    • Subscription: Choose your Azure subscription.
    • Resource group: Create a new one (e.g., transcription-services) or select an existing one.
    • Region: Select a region where the service will be hosted (e.g., East US). You will need this value later.
    • Name: Give your resource a unique name (e.g., fspbx-speech-service).
    • Pricing tier: Select a tier. For testing and low-volume use, the Free F0 tier is an excellent choice.
    • Review the terms and click Review + create, then Create.

  4. Wait for Deployment: Azure will take a minute or two to deploy the resource. Once it's complete, click Go to resource.

Step 2: Retrieve API Key and Region​

After the resource is created, you need to get the credentials required by the application.

  1. Navigate to the Speech service resource you just created.
  2. In the left-hand menu, under Resource Management, click on Keys and Endpoint.
  3. Copy the Credentials:
    • Key: You will see two keys (KEY 1 and KEY 2). You only need one. Copy the value of KEY 1.
    • Location/Region: This value should match the region you chose during creation. Copy this value as well (e.g., eastus).

Step 3: Configuration​

We will now configure the application to use the Azure credentials.

1. Update Environment Variables (.env)​

Add the following section to your .env file and populate it with the key and region you copied from the Azure Portal.

# --- AZURE SPEECH-TO-TEXT CREDENTIALS ---
AZURE_API_KEY="paste_your_key_1_value_here"
AZURE_SPEECH_REGION="paste_your_region_value_here"

2. Clear Configuration Cache​

To ensure FS PBX loads the new environment variables, run the following commands:

cd /var/www/fspbx
php artisan config:cache
php artisan queue:restart

Step 4: Activate the Azure Transcription Provider​

Once the credentials are in place, the final step is to instruct the application to use Azure for new voicemail transcriptions.

  1. In the FS PBX user interface, navigate to the Default Settings section and then select Voicemail.
  2. Locate the setting named voicemail_queue_strategy. Update its value to modern.
  3. Locate the setting named transcribe_provider. Update its value to azure.
  4. Save the changes.

All new voicemails will now be sent to Azure Cognitive Services for transcription.

Troubleshooting​

Checking the Logs​

The first place to check for any transcription issues is the main FS PBX log file.

The log is located at: /var/www/fspbx/storage/logs/laravel.log

To watch the log file for new errors in real-time, open a terminal on your PBX server and run the following command. Leave this command running while you trigger a new voicemail transcription. Any errors generated by the process will appear in your terminal instantly.

tail -f /var/www/fspbx/storage/logs/laravel.log

Error: 401 Unauthorized​

This is the most common error and indicates an authentication problem.

  • Cause 1: The AZURE_API_KEY in your .env file is incorrect or has a typo. Double-check that it was copied correctly from the Azure Portal.
  • Cause 2: The AZURE_SPEECH_REGION is incorrect. The region is part of the API endpoint URL, and a mismatch can cause authentication to fail.

Error: 404 Not Found / 403 Forbidden​

This can occur if the API endpoint URL is constructed incorrectly or if your service has exceeded its quota.

  • Cause 1: The AZURE_SPEECH_REGION in your .env file is invalid or contains a typo. For example, using East US instead of eastus. Verify the correct region identifier in the Azure Portal under "Keys and Endpoint".
  • Cause 2: If you are on the Free F0 pricing tier, you may have exceeded the monthly usage limit. Check your usage metrics in the Azure Portal.